home *** CD-ROM | disk | FTP | other *** search
Text File | 1990-10-14 | 39.0 KB | 1,019 lines |
- Newsgroups: comp.sources.misc
- X-UNIX-From: dvadura@watdragon.waterloo.edu
- subject: v15i063: dmake version 3.6 (part 11/25)
- from: Dennis Vadura <dvadura@watdragon.waterloo.edu>
- Sender: allbery@uunet.UU.NET (Brandon S. Allbery - comp.sources.misc)
-
- Posting-number: Volume 15, Issue 63
- Submitted-by: Dennis Vadura <dvadura@watdragon.waterloo.edu>
- Archive-name: dmake-3.6/part11
-
- #!/bin/sh
- # this is part 11 of a multipart archive
- # do not concatenate these parts, unpack them in order with /bin/sh
- # file man/dmake.tf continued
- #
- CurArch=11
- if test ! -r s2_seq_.tmp
- then echo "Please unpack part 1 first!"
- exit 1; fi
- ( read Scheck
- if test "$Scheck" != $CurArch
- then echo "Please unpack part $Scheck next!"
- exit 1;
- else exit 0; fi
- ) < s2_seq_.tmp || exit 1
- echo "x - Continuing file man/dmake.tf"
- sed 's/^X//' << 'SHAR_EOF' >> man/dmake.tf
- Xthe recipe may not span across multiple makefiles.
- XAny targets and prerequisites found on a target definition line are taken
- Xto be white space separated tokens.
- XThe rule operator (\fIop\fP in SYNTAX section) is also considered
- Xto be a token but does not require
- Xwhite space to precede or follow it. Since the rule operator begins with a `:',
- Xtraditional versions of make do not allow the `:' character to
- Xform a valid target name. \fBdmake\fP allows `:' to be present in
- Xtarget/prerequisite names as long as the entire target/prerequisite name is
- Xquoted. For example:
- X.sp
- X\ta:fred : test
- X.sp
- Xwould be parsed as TARGET = a, PREREQUISITES are fred, :, and test, which
- Xis not what was intended. To fix this you must write:
- X.sp
- X\t"a:fred" : test
- X.sp
- XWhich will be parsed as expected.
- XSee the EXAMPLES section for how to apply this to a list of targets.
- X.SH ATTRIBUTES
- X.B dmake
- Xdefines several target attributes. Attributes may be
- Xassigned to a single target, a group of targets, or to all targets in the
- Xmakefile. Attributes are used to modify
- X\fBdmake\fP actions during target update.
- XThe recognized attributes are:
- X.sp
- X.IP \fB.EPILOG\fP 1.2i
- XInsert shell epilog code when executing a group recipe associated with
- Xany target having this attribute set.
- X.IP \fB.IGNORE\fP 1.2i
- XIgnore an error when trying to make any target with this attribute set.
- X.IP \fB.LIBRARY\fP 1.2i
- XTarget is a library.
- X.IP \fB.MKSARGS\fP 1.2i
- XIf in an MSDOS environment then use MKS extended argument passing
- Xconventions to pass arguments to commands. Non-MSDOS
- Xenvironments ignore this attribute.
- X.IP \fB.NOINFER\fP 1.2i
- XAny target with this attribute set will not be subjected
- Xto transitive closure if it is inferred as a prerequisite
- Xof a target whose recipe and prerequisites are being inferred.
- X(i.e. the inference algorithm will not use any prerequisite with this attribute
- Xset, as a target)
- X.IP \fB.PRECIOUS\fP 1.2i
- XDo not remove this target under any circumstances.
- XSet by default for any targets whose corresponding files exist in the file
- Xsystem prior to the execution of \fBdmake\fP.
- X.IP \fB.PROLOG\fP 1.2i
- XInsert shell prolog code when executing a group recipe associated with
- Xany target having this attribute set.
- X.IP \fB.SEQUENTIAL\fP 1.2i
- XForce a sequential make of the associated target's prerequisites.
- X.IP \fB.SETDIR\fP 1.2i
- XChange current working directory to specified directory when making the
- Xassociated target. You must
- Xspecify the directory at the time the attribute is specified. To do this
- Xsimply give \fI.SETDIR=path\fP as the attribute. \fIpath\fP is expanded and
- Xthe result is used as the value of the directory to change to.
- XIf path is surrounded by single quotes then path is not expanded, and is used
- Xliterally as the directory name.
- XIf the \fIpath\fP contains any `:' characters then the entire attribute string
- Xmust be quoted using ".
- XIf a target having this attribute set also has the .IGNORE
- Xattribute set then if the change to the specified directory fails it will be
- Xignored, and no error message will be issued.
- X.IP \fB.SILENT\fP 1.2i
- XDo not echo the recipe lines when making any target with this attribute set,
- Xand do not issue any warnings.
- X.IP \fB.SWAP\fP 1.2i
- XUnder MSDOS
- Xwhen making a target with this attribute set swap the \fBdmake\fP executable
- Xto disk prior to executing the recipe line.
- X.IP \fB.SYMBOL\fP 1.2i
- XTarget is a library member and is an entry point into a module in the
- Xlibrary. This attribute is used only when searching a library for a target.
- XTargets of the form lib((entry)) have this attribute set automatically.
- X.IP \fB.USESHELL\fP 1.2i
- XForce each recipe line of a target to be executed using a shell.
- XSpecifying this attribute is equivalent to specifying the '+' character at the
- Xstart of each line of a non-group recipe.
- X.IP \fB.UPDATEALL\fP 1.2i
- XIndicates that all the targets listed in this rule are updated by the
- Xexecution of the accompanying recipe.
- XA common example is the production of the
- X.I y.tab.c
- Xand
- X.I y.tab.h
- Xfiles by
- X.B yacc
- Xwhen it is run on a grammar. Specifying .UPDATEALL in such a rule
- Xprevents the running of yacc twice, once for the y.tab.c file and once
- Xfor the y.tab.h file.
- X.sp
- X.PP
- XAll attributes are user setable and except for .UPDATEALL and .MKSARGS
- Xmay be used in one of two forms.
- XThe .MKSARGS attribute is restricted to use as a global attribute, and
- Xthe use of the .UPDATEALL attribute is restricted to rules of the second
- Xform only.
- X.sp
- X\tATTRIBUTE_LIST : \fItargets\fP
- X.sp
- Xassigns the attributes specified by ATTRIBUTE_LIST to each target in
- X.I targets
- Xor
- X.sp
- X\t\fItargets\fP ATTRIBUTE_LIST : ...
- X.sp
- Xassigns the attributes specified by ATTRIBUTE_LIST to each target in
- X.I targets.
- XIn the first form if
- X.I targets
- Xis empty (ie. a NULL list), then the
- Xlist of attributes will apply to all targets in the makefile
- X(this is equivalent to the common Make construct of \fI".IGNORE :"\fP
- Xbut has been modified to the notion of an attribute instead of
- Xa special target).
- XNot all of the attributes have global meaning.
- XIn particular, .LIBRARY, .SYMBOL, and .UPDATEALL
- Xhave no assigned global meaning.
- X.PP
- XAny attribute may be used with any target, even with the special targets.
- XSome combinations are useless (e.g. .INCLUDE .PRECIOUS: ... ),
- Xwhile others are useful (e.g. .INCLUDE .IGNORE : "file.mk" will not complain
- Xif file.mk cannot be found using the include file search rules,
- Xsee the section on SPECIAL TARGETS for a description of .INCLUDE).
- XIf a specified attribute will not be used with the special target a warning
- Xis issued and the attribute is ignored.
- X.SH MACROS
- X.B dmake
- Xsupports six types of macro assignment.
- X.sp
- X.IP "\fBMACRO = LINE\fP" 1.55i
- XThis is the most common and familiar form of macro assignment. It assigns
- XLINE literally as the value of MACRO.
- XFuture expansions of MACRO recursively expand it's value.
- X.IP "\fBMACRO *= LINE\fP" 1.55i
- XThis form behaves exactly as the simple '=' form with the exception that if
- XMACRO already has a value then the assignment is not performed.
- X.IP "\fBMACRO := LINE\fP" 1.55i
- XThis form differs from the simple '=' form in that it expands LINE
- Xprior to assigning it as the value of MACRO.
- XFuture expansions of MACRO do not recursively expand it's value.
- X.IP "\fBMACRO *:= LINE\fP" 1.55i
- XThis form behaves exactly as the ':=' form with the exception that if
- XMACRO already has a value then the assignment and expansion are not performed.
- X.IP "\fBMACRO += LINE\fP" 1.55i
- XThis form of macro assignment allows macro values to grow. It takes the
- Xliteral value of LINE and appends it to the previous value of MACRO separating
- Xthe two by a single space.
- XFuture expansions of MACRO recursively expand it's value.
- X.IP "\fBMACRO +:= LINE\fP" 1.55i
- XThis form is similar to the '+=' form except that the value of LINE is expanded
- Xprior to being added to the value of MACRO.
- X.PP
- XMacro expressions specified on the command line allow the macro value
- Xto be redefined within the makefile only if the macro is defined using
- Xthe '+=' and '+:=' operators. Other operators will define a macro that cannot
- Xbe further modified.
- X.PP
- XWhen \fBdmake\fP defines a non-environment macro it strips leading and
- Xtrailing white space from the macro value.
- XMacros imported from the environment via either the .IMPORT special
- Xtarget (see the SPECIAL TARGETS section), or the \fB-e\fP, or \fB-E\fP flags
- Xare an exception to this rule. Their values are
- Xalways taken literally and white space is never stripped.
- XIn addition, macros defined using the .IMPORT special target do
- Xnot have their values expanded when they are used within a makefile.
- XIn contrast, environment macros that are imported
- Xdue to the specification of the \fB-e\fP or \fB-E\fP flags
- Xare subject to expansion when used.
- X.PP
- XTo specify a macro expansion
- Xenclose the name in () or {} and precede it with a dollar sign $.
- XThus $(TEST) represents an expansion of the macro variable named TEST.
- XIf TEST is
- Xdefined then $(TEST) is replaced by its expanded value. If TEST is not
- Xdefined then $(TEST) expands to the NULL string (this is equivalent to
- Xdefining a macro as 'TEST=' ). A short form may be used for single character
- Xnamed macros. In this case the parentheses are optional, and $(I) is
- Xequivalent to $I.
- XMacro expansion is recursive, hence, if the value string contains an expression
- Xrepresenting a macro expansion, the expansion is performed. Circular macro
- Xexpansions are detected and cause an error to be issued.
- X.PP
- XWhen defining a macro the given macro name is first expanded before being used
- Xto define the macro. Thus it is possible to define macros whose names
- Xdepend on values of other macros. For example, suppose
- X.sp
- X\tCWD = $(PWD:b)
- X.sp
- Xis defined, then the value of $(CWD) is the name of the current directory.
- XThis can be used to define macros specific to this directory, for
- Xexample:
- X.sp
- X\t_$(CWD).prt = list of files to print...
- X.sp
- XThe actual name of the defined macro is a function of the current directory.
- XA construct such as this is useful when processing a hierarchy of directories
- Xusing .SETDIR attributed targets and a collection of small distributed
- Xmakefile stubs.
- X.PP
- XMacro variables may be defined within the makefile, on the command
- Xline, or imported from the environment.
- X.PP
- X.B \fBdmake\fR
- Xsupports several non-standard macro expansions:
- XThe first is of the form:
- X.RS
- X.IP \fI$(macro_name:modifier_list:modifier_list:...)\fR
- X.RE
- X.LP
- Xwhere
- X.I modifier_list
- Xis chosen from the set { D or d, F or f, B or b, S or s, T or t } and
- X.RS
- X.sp
- X.Is "d "
- X.Ii "d "
- X\- directory portion of all path names
- X.Ii "f"
- X\- file (including suffix) portion of path names
- X.Ii "b"
- X\- file (not including suffix) portion of path names
- X.Ii "s"
- X\- simple pattern substitution
- X.Ii "t"
- X\- tokenization.
- X.sp
- X.RE
- XThus if we have the example:
- X.LP
- X\ttest = d1/d2/d3/a.out f.out d1/k.out
- X.LP
- XThe following macro expansions produce the values on the right of '-->' after
- Xexpansion.
- X.RS
- X.sp
- X.Is "$(test:s/out/in/:f) "
- X.Ii "$(test:d)"
- X--> d1/d2/d3/ d1/
- X.Ii "$(test:b)"
- X--> a f k
- X.Ii "$(test:f)"
- X--> a.out f.out k.out
- X.Ii "${test:db}"
- X--> d1/d2/d3/a f d1/k
- X.Ii "${test:s/out/in/:f}"
- X--> a.in f.in k.in
- X.Ii $(test:f:t"+")
- X--> a.out+f.out+k.out
- X.RE
- X.PP
- XIf a token ends in a string composed from the value of the macro DIRBRKSTR
- X(ie. ends in a directory separator string, e.g. '/' in UNIX) and you use the
- X\fB:d\fP modifier then the expansion returns the directory name less the
- Xfinal directory separator string. Thus successive pairs of :d modifiers
- Xeach remove a level of directory in the token string.
- X.PP
- XThe tokenization modifier takes all white space separated tokens from the
- Xmacro value and separates them by the quoted separator string. The separator
- Xstring may contain the following escape codes \\a => <bel>,
- X\&\\b => <backspace>, \\f => <formfeed>, \\n => <nl>, \\r => <cr>,
- X\&\\t => <tab>, \\v => <vertical tab>, \\" => ", and \\xxx => <xxx> where
- Xxxx is the octal representation of a character. Thus the
- Xexpansion:
- X.LP
- X.RS
- X.nf
- X$(test:f:t"+\\n")
- X.RE
- Xproduces:
- X.RS
- Xa.out+
- Xf.out+
- Xk.out
- X.fi
- X.RE
- X.PP
- XThe second non-standard form of macro expansion allows for recursive macros.
- XIt is possible to specify a $(\fImacro_name\fR) or ${\fImacro_name\fR} expansion
- Xwhere \fImacro_name\fR contains more $( ... ) or ${ ... } macro expansions
- Xitself.
- X.PP
- XFor example $(CC$(_HOST)$(_COMPILER)) will first expand CC$(_HOST)$(_COMPILER)
- Xto get a result and use that result as the name of the macro to expand.
- XThis is useful for writing a makefile for more than one target
- Xenvironment. As an example consider the following hypothetical case.
- XSuppose that _HOST and _COMPILER are imported from the environment
- Xand are set to represent the host machine type and the host compiler
- Xrespectively.
- X.RS
- X.sp
- X.nf
- XCFLAGS_VAX_CC = -c -O # _HOST == "_VAX", _COMPILER == "_CC"
- XCFLAGS_PC_MSC = -c -ML # _HOST == "_PC", _COMPILER == "_MSC"
- X.sp
- X# redefine CFLAGS macro as:
- X.sp
- XCFLAGS := $(CFLAGS$(_HOST)$(_COMPILER))
- X.fi
- X.sp
- X.RE
- XThis causes CFLAGS to take on a value that corresponds to the
- Xenvironment in which the make is being invoked.
- X.PP
- XThe final non-standard macro expansion is of the form:
- X.RS
- X.sp
- Xstring1{token_list}string2
- X.RE
- X.LP
- Xwhere string1, string2 and token_list are expanded. After expansion,
- Xstring1 is prepended to each token found in token_list and
- Xstring2 is appended to each resulting token from the previous prepend.
- Xstring1 and string2 are not delimited by white space
- Xwhereas the tokens in token_list are. A null token in the token list
- Xis specified using "".
- XThus using another example we have:
- X.RS
- X.sp
- X.Is "test/{ f1 ""f2"" """" }.o "
- X.Ii "test/{f1 f2}.o"
- X--> test/f1.o test/f2.o
- X.Ii "test/ {f1 f2}.o"
- X--> test/ f1.o f2.o
- X.Ii "test/{f1 f2} .o"
- X--> test/f1 test/f2 .o
- X.Ii "test/{ f1 ""f2"" """" }.o"
- X--> test/f1.o test/f2.o test/.o
- X.sp
- X.Ii and
- X.sp
- X.Is "test/{ d1 d2 }/{ f1 f2 }.o --> "
- X.Ii "test/{ d1 d2 }/{ f1 f2 }.o --> "
- Xtest/d1/f1.o test/d1/f2.o
- Xtest/d2/f1.o test/d2/f2.o
- X.sp
- X.RE
- XSee the SPECIAL MACROS section for a description of the special macros that
- X\fBdmake\fP defines and understands.
- X.SH "RULES AND TARGETS"
- XA makefile contains a series of entries that specify dependencies.
- XSuch entries are called \fItarget/prerequisite\fP or \fIrule\fP definitions.
- XEach rule definition
- Xis optionally followed by a set of lines that provide a recipe for updating
- Xany targets defined by the rule.
- XWhenever
- X.B dmake
- Xattempts to bring a target up to date and an explicit recipe is provided with
- Xa rule defining the target, that recipe is used to update the
- Xtarget. A rule definition begins with a line having the following syntax:
- X.sp
- X.RS
- X.nf
- X\fI<targets>\fP [\fI<attributes>\fP] \fI<ruleop>\fP [\fI<prerequisites>\fP] [;\fI<recipe>\fP]
- X.fi
- X.RE
- X.sp
- X.I targets
- Xis a non-empty list of targets. If the target is a
- Xspecial target (see SPECIAL TARGETS section below) then it must appear alone
- Xon the rule line. For example:
- X.sp
- X.RS
- X\&.IMPORT .ERROR : ...
- X.RE
- X.sp
- Xis not allowed since both .IMPORT and .ERROR are special targets.
- XSpecial targets are not used in the construction of the dependency graph and
- Xwill not be made.
- X.PP
- X.I attributes
- Xis a possibly empty list of attributes. Any attribute defined in the
- XATTRIBUTES section above may be specified. All attributes will be applied to
- Xthe list of named targets in the rule definition. No other targets will
- Xbe affected.
- X.sp
- X.IP NOTE: 0.75i
- XAs stated earlier,
- Xif both the target list and prerequisite list are empty but the attributes
- Xlist is not, then the specified attributes affect all targets in the makefile.
- X.sp
- X.PP
- X.I ruleop
- Xis a separator which is used to identify the targets from the prerequisites.
- XOptionally it also provides a facility for modifying the way in which
- X.B dmake
- Xhandles the making of the associated targets.
- XIn its simplest form the operator is a single ':', and need not be separated
- Xby white space from its neighbouring tokens. It may additionally be followed
- Xby any of the modifiers { !, ^, -, : }, where:
- X.sp
- X.IP \fB!\fP
- Xsays execute the recipe for the associated targets once for each out of date
- Xprerequisite. Ordinarily the recipe is executed
- Xonce for all out of date prerequisites at the same time.
- X.IP \fB^\fP
- Xsays to insert the specified prerequisites, if any, before any
- Xother prerequisites already associated with the specified targets.
- XIn general, it is not useful to specify ^ with an empty
- Xlist of prerequisites.
- X.IP \fB-\fP
- Xsays to clear the previous list of prerequisites before adding
- Xthe new prerequisites. Thus,
- X.sp
- X\t.SUFFIXES :
- X.br
- X\t.SUFFIXES : .a .b
- X.sp
- Xcan be replaced by
- X.sp
- X\t.SUFFIXES :- .a .b
- X.sp
- Xhowever the old form still works as expected. NOTE: .SUFFIXES is ignored by
- X.B dmake
- Xit is used here simply as an example.
- X.IP \fB:\fP
- XWhen the rule operator is not modified by a second ':'
- Xonly one set of rules may be specified for making a target.
- XMultiple definitions may be used to add to the
- Xlist of prerequisites that a target depends on.
- XHowever, if a target is multiply defined
- Xonly one definition may specify a recipe
- Xfor making the target.
- X.sp
- XWhen a target's rule operator is modified by a second ':'
- X(:: for example) then this definition may not be the only
- Xdefinition with a recipe for the target. There may be other :: target
- Xdefinition lines that specify a different set of prerequisites with a
- Xdifferent recipe for updating the target.
- XAny such target is made if any of the definitions
- Xfind it to be out of date
- Xwith respect to the related prerequisites
- Xand the corresponding recipe is used to update the
- Xtarget.
- X.sp
- XIn the following simple example, each rule has a `::' \fIruleop\fP. In such an
- Xoperator we call the first `:' the operator, and the second `:' the modifier.
- X.sp
- X.nf
- Xa.o :: a.c b.h
- X first recipe for making a.o
- X
- Xa.o :: a.y b.h
- X second recipe for making a.o
- X.fi
- X.sp
- XIf a.o is found to be out of date with respect to a.c then the first recipe
- Xis used to make a.o. If it is found out of date with respect to a.y then
- Xthe second recipe is used. If a.o is out of date with respect to
- Xb.h then both recipes are invoked to make a.o.
- XIn the last case the order of invocation corresponds to the order in which the
- Xrule definitions appear in the makefile.
- X.PP
- XTargets defined using a single `:' operator
- Xwith a recipe may be redefined again with a new recipe by using a
- X`:' operator with a `:' modifier.
- XThis is equivalent to a target having been
- Xinitially defined with a rule using a `:' modifier.
- XOnce a target is defined using a `:'
- Xmodifier it may not be defined again with a recipe using only the `:' operator
- Xwith no `:' modifier. In both cases the use of a `:' modifier creates a new
- Xlist of prerequisites and makes it the current prerequisite list for the target.
- XThe `:' operator with no recipe always modifies the current list
- Xof prerequisites.
- XThus assuming each of the following definitions has a recipe attached, then:
- X.RS
- X.sp
- X.nf
- Xjoe : fred ... (1)
- Xjoe :: more ... (2)
- X.sp
- Xand
- X.sp
- Xjoe :: fred ... (3)
- Xjoe :: more ... (4)
- X.sp
- X.fi
- X.RE
- Xare legal and mean: add the recipe associated with (2), or (4) to the set
- Xof recipes for joe, placing them after existing recipes for
- Xmaking joe.
- XThe constructs:
- X.RS
- X.sp
- X.nf
- Xjoe :: fred ... (5)
- Xjoe : more ... (6)
- X.sp
- Xand
- X.sp
- Xjoe : fred ... (7)
- Xjoe : more ... (8)
- X.sp
- X.fi
- X.RE
- Xare errors since we have two sets of perfectly good recipes for
- Xmaking the target.
- X.PP
- X.I prerequisites
- Xis a possibly empty list of targets that must be brought up to date before
- Xmaking the current target.
- X.PP
- X.I recipe
- Xis a short form and allows the user to specify short rule definitions
- Xon a single line.
- XIt is taken to be the first recipe line in a larger recipe
- Xif additional lines follow the rule definition.
- XIf the semi-colon is present but the recipe line is empty (ie. null string)
- Xthen it is taken
- Xto be an empty rule. Any target so defined causes the
- X.I "Don't know how to make ..."
- Xerror message to be suppressed when
- X.B dmake
- Xtries to make the target and fails.
- XThis silence is maintained for rules that are terminated
- Xby a semicolon and have no following recipe lines, for targets listed on the
- Xcommand line, and for the first target found in the makefile.
- X.SH "RECIPES"
- XThe traditional format used by most versions of Make defines the recipe
- Xlines as arbitrary strings that may contain macro expansions. They
- Xfollow a rule definition line and may be spaced
- Xapart by comment or blank lines.
- XThe list of recipe lines defining the recipe is terminated by a new target
- Xdefinition, a macro definition, or end-of-file.
- XEach recipe line
- X.B MUST
- Xbegin with a \fB<TAB>\fP character which
- Xmay optionally be followed with one or all
- Xof the characters
- X.IR "'@%+\-'" "."
- XThe
- X.I "'\-'"
- Xindicates that non-zero exit values (ie. errors)
- Xare to be ignored when this recipe line is executed, the
- X.I "'\+'"
- Xindicates that the current recipe line is to be executed using the shell, the
- X.I "'%'"
- Xindicates that
- X.B dmake
- Xshould swap itself out to secondary storage (MSDOS only) before running the
- Xrecipe and the
- X.I "'@'"
- Xindicates that the recipe line should NOT be echoed to the terminal prior to
- Xbeing executed. Each switch is off by default
- X(ie. by default, errors are significant, commands are echoed, no swapping is
- Xdone and a shell is
- Xused only if the recipe line contains a character found in the value of the
- XSHELLMETAS macro).
- XGlobal settings activated via command line options or special attribute or
- Xtarget names may also affect these settings.
- XAn example recipe:
- X.sp
- X.RS
- X.nf
- Xtarget :
- X\tfirst recipe line
- X\tsecond recipe line, executed independently of the first.
- X\t@a recipe line that is not echoed
- X\t\-and one that has errors ignored
- X\t%and one that causes dmake to swap out
- X\t\+and one that is executed using a shell.
- X.fi
- X.RE
- X.PP
- XThe second and new format of the recipe block begins the block with the
- Xcharacter '[' (the open group character) in the last non-white space
- Xposition of a line, and terminates the
- Xblock with the character ']' (the close group character)
- Xin the first non-white space position of a line.
- XIn this form each recipe line need not have a leading TAB. This is
- Xcalled a recipe group. Groups so defined are fed intact as a single
- Xunit to a shell for execution whenever the corresponding target needs to
- Xbe updated. If the open group character '[' is preceded
- Xby one or all of \-, @ or %
- Xthen they apply to the entire group in the same way that they
- Xapply to single recipe lines. You may also specify '+' but it is
- Xredundant as a shell is already being used to run the recipe.
- XSee the MAKING TARGETS section for a description of how
- X.B dmake
- Xinvokes recipes.
- XHere is an example of a group recipe:
- X.sp
- X.RS
- X.nf
- Xtarget :
- X[
- X\tfirst recipe line
- X\tsecond recipe line
- X\tall of these recipe lines are fed to a
- X\tsingle copy of a shell for execution.
- X]
- X.fi
- X.RE
- X.sp
- X.SH "TEXT DIVERSIONS"
- X.B dmake
- Xsupports the notion of text diversions.
- XIf a recipe line contains the macro expression
- X.RS
- X.sp
- X$(mktmp[,\fIname_modifier\fP] \fIdata\fP)
- X.sp
- X.RE
- Xthen all text contained in the \fIdata\fP expression is expanded and
- Xis written to a new temporary file. The name of that file is then returned
- Xas the value of the macro expansion and is substituted for the text of the
- Xmacro expression if no \fIname_modifier\fP is present.
- X.PP
- X.I data
- Xcan be any text and must be separated from the 'mktmp' portion of the
- Xmacro name by white-space. The only restriction on the data text is that
- Xit must contain an balanced number of parentheses of the same kind as are
- Xused to initiate the $(mktmp ...) expression. For example:
- X.sp
- X\t$(mktmp $(XXX))
- X.sp
- Xis legal and works as expected, but:
- X.sp
- X\t$(mktmp text (to dump to file)
- X.sp
- Xis not legal. You can achieve what you wish by either defining a macro that
- Xexpands to '(' or by using {} in the macro expression; like this:
- X.sp
- X\t${mktmp text (to dump to file}
- X.sp
- Xwhich works as expected. Since the temporary file is opened when the
- Xmacro containg the text diversion expression is expanded, diversions may
- Xnow be nested and any diversions that are created as part of ':=' macro
- Xexpansions persist for the duration of the
- X.B dmake
- Xrun.
- XThe diversion text may contain
- Xthe same escape codes as those described in the MACROS section.
- XThus if the \fIdata\fP text is to contain new lines they must be inserted
- Xusing the \\n escape sequence. For example the expression:
- X.RS
- X.sp
- X.nf
- Xall:
- X cat $(mktmp this is a\\n\\
- X test of the text diversion\\n)
- X.fi
- X.sp
- X.RE
- Xis replaced by:
- X.RS
- X.sp
- Xcat /tmp/mk12294AA
- X.sp
- X.RE
- Xwhere the temporary file contains two lines both of which are terminated
- Xby a new-line. If the \fIdata\fP text spans multiple lines in the makefile
- Xthen each line must be continued via the use of a \\.
- XA second more illustrative example generates a response file to an MSDOS
- Xlink command:
- X.RS
- X.sp
- X.nf
- XOBJ = fred.obj mary.obj joe.obj
- Xall : $(OBJ)
- X link @$(mktmp $(^:t"+\\n")\\n)
- X.fi
- X.sp
- X.RE
- XThe result of making `all' in the second example is the command:
- X.RS
- X.sp
- Xlink @/tmp/mk02394AA
- X.sp
- X.RE
- Xwhere the temporary file contains:
- X.RS
- X.sp
- X.nf
- Xfred.obj+
- Xmary.obj+
- Xjoe.obj
- X.fi
- X.sp
- X.RE
- XThe last line of the file is terminated by a new-line which is inserted
- Xdue to the \\n found at the end of the \fIdata\fP string.
- X.PP
- XIf the optional
- X.I name_modifier
- Xis supplied in the diversion expression then the returned value of the
- Xexpression is the expanded value of \fIname_modifier\fP. Together with
- Xthe special macros TMPFILE and USESHELL this can be
- Xused to alter the name of the temporary file returned as the result of the
- X$(mktmp ...) expansion.
- X.PP
- XUnder MS-DOS text diversions may be a problem. Many DOS tools require
- Xthat path names which contain directories use the \\ character to delimit
- Xthe directories. Some users however wish to use the '/' to delimit pathnames
- Xon their system and use environments that allow them to do so. These
- Xenvironments usually accept the \\ delimited path names as well.
- XIn order to allow the user the most flexibility
- X.B dmake
- Xdefines three macros that can be used when text diversion file names are being
- Xplaced into the recipe text to be executed. The macro TMPFILE contains
- Xthe name of the most recently opened temporary file, and
- Xthe macro, USESHELL, is set to "yes" if the
- Xcurrent recipe is forced to use a shell via the .USESHELL or '+' directives,
- Xotherwise its value is "no".
- XIn the absence of a \fIname_modifier\fP in the diversion expression the result
- Xof expanding the diversion expression is the value of TMPFILE.
- XThe
- X.B dmake
- Xstartup files define the macro DIVFILE whose value is either the
- Xvalue of TMPFILE or the value of TMPFILE editted to replace any '/' characters
- Xto the appropriate value based on the current shell and whether it will be
- Xused to execute the recipe.
- X.PP
- XPrevious versions of
- X.B dmake
- Xdefined text diversions using <+, +> strings,
- Xwhere <+ started a text diversion and +> terminated one.
- X.B dmake
- Xis backward compatible with this construct if the <+ and +> appear literally
- Xon the same recipe line or in the same macro value string. In such instances
- Xthe expression:
- X.sp
- X\t<+data text+>
- X.sp
- Xis mapped to:
- X.sp
- X\t$(mktmp data text)
- X.sp
- Xwhich is fully output compatible with the earlier construct. <+, +>
- Xconstructs whose text spans multiple lines must be converted by hand to use
- X$(mktmp ...).
- X.PP
- XIf the environment variable TMPDIR is defined then the
- Xtemporary file is placed into the directory specified by that variable.
- XA makefile can modify the location of temporary files by
- Xdefining a macro named TMPDIR and exporting it using the .EXPORT special
- Xtarget.
- X.SH "SPECIAL TARGETS"
- XThis section describes the special targets that are recognized by \fBdmake\fP.
- XSome are affected by attributes and others are not.
- X.IP \fB.ERROR\fP 1.4i
- XIf defined then the recipe associated with this target is executed
- Xwhenever an error condition is detected by \fBdmake\fP. All attributes that
- Xcan be used with any other target may be used with this target. Any
- Xprerequisites of this target will be brought up to date during it's processing.
- XNOTE: errors will be ignored while making this target, in extreme cases this
- Xmay cause some problems.
- X.IP \fB.EXPORT\fP 1.4i
- XAll prerequisites associated with this target are assumed to
- Xcorrespond to macro names and they and their values
- Xare exported to the environment as environment strings at the point in
- Xthe makefile at which this target appears.
- XAny attributes specified with this target are ignored.
- XOnly macros which have been assigned a value in the makefile prior to the
- Xexport directive are exported, macros as yet undefined are not exported.
- X.IP \fB.IMPORT\fP 1.4i
- XPrerequisite names specified for this target are searched for in the
- Xenvironment and defined as macros with their value taken from the environment.
- XIf the name cannot be found in the environment an error message is issued.
- X\&.IMPORT accepts the .IGNORE attribute. When given, it causes \fBdmake\fP
- Xto ignore the above error.
- XSee the MACROS section for a description of the processing of imported macro
- Xvalues.
- X.IP \fB.INCLUDE\fP 1.4i
- XParse another makefile just as if it had been located at the point of the
- X\&.INCLUDE in the current makefile. The list of prerequisites gives the list of
- Xmakefiles to try to read. If the list contains multiple makefiles then they
- Xare read in order from left to right. The following search rules are used
- Xwhen trying to locate the file. If the filename is surrounded by " or just
- Xby itself then it is searched for in the current directory. If it is not
- Xfound it is then searched for in each of the directories specified for the
- X\&.INCLUDEDIRS special target. If the file name is surrounded by < and >, (ie.
- X<my_spiffy_new_makefile>) then it is searched for only in the directories
- Xgiven by the .INCLUDEDIRS special target. In both cases if the file name is a
- Xfully qualified name starting at the root of the file system then it is only
- Xsearched for once, and the .INCLUDEDIRS list is ignored. .INCLUDE accepts
- Xthe .IGNORE and .SETDIR attributes. If .IGNORE attribute is given and the file
- Xcannot be found then \fBdmake\fP continues processing,
- Xotherwise an error message is generated.
- XThe .SETDIR attribute causes
- X.B dmake
- Xto change directories to the specified directory prior to attempting the
- Xinclude operation.
- X.IP \fB.INCLUDEDIRS\fP 1.4i
- XThe list of prerequisites specified for this target defines the set of
- Xdirectories to search when trying to include a makefile.
- X.IP \fB.MAKEFILES\fP 1.4i
- XThe list of prerequisites is the set of files to try to read as the default
- Xmakefile. By default this target is defined as:
- X.sp
- X\t\&.MAKEFILES : makefile.mk Makefile makefile
- X.sp
- X.IP \fB.SOURCE\fP 1.4i
- XThe prerequisite list of this target defines a set of directories to check
- Xwhen trying to locate a target file name. See the section on BINDING of
- Xtargets for more information.
- X.IP \fB.SOURCE.suff\fP 1.4i
- XThe same as .SOURCE, except that the .SOURCE.suff list is searched first when
- Xtrying to locate a file matching the a target whose name ends in the suffix
- X\&.suff.
- X.IP \fB.REMOVE\fP 1.4i
- XThe recipe of this target is used whenever \fBdmake\fP needs to remove
- Xintermediate targets that were made but do not need to be kept around.
- XSuch targets result from the application of transitive closure on the
- Xdependency graph.
- X.PP
- XIn addition to the special targets above,
- Xseveral other forms of targets are recognized and are considered special,
- Xtheir exact form and use is defined in the sections that follow.
- X.SH "SPECIAL MACROS"
- X.B dmake
- Xdefines a number of special macros. They are divided into three classes:
- Xcontrol macros, run-time macros, and function macros.
- XThe control macros are used by
- X.B dmake
- Xto configure it's actions, and are the preferred method of doing so.
- XIn the case when a control macro has the same function as a special
- Xtarget or attribute they share the same name as the special target or
- Xattribute.
- XThe run-time macros are defined when
- X.B dmake
- Xmakes targets and may be used by the user inside recipes.
- XThe function macros provide higher level functions dealing with macro
- Xexpansion and diversion file processing.
- X.SH "CONTROL MACROS"
- XTo use the control macros simply assign them a value just like any other
- Xmacro. The control macros are divided into three groups:
- Xstring valued macros, character valued macros, and boolean valued macros.
- X.PP
- XThe following are all of the string valued macros.
- XThis list is divided into two groups. The first group gives the string
- Xvalued macros that are defined internally and cannot be directly set by the
- Xuser.
- X.IP \fBDIRBRKSTR\fP 1.4i
- XContains the string of chars used to terminate
- Xthe name of a directory in a pathname.
- XUnder UNIX it's value is "/", under MSDOS it's value is "/\\:".
- X.IP \fBINCDEPTH\fP 1.4i
- XThis macro's value is a string of digits representing
- Xthe current depth of makefile inclusion.
- XIn the first makefile level this value is zero.
- X.IP \fBMFLAGS\fP 1.4i
- XIs the list of flags
- Xthat were given on the command line including a leading switch character.
- XThe -f flag is not included in this list.
- X.IP \fBMAKECMD\fP 1.4i
- XIs the name with which \fBdmake\fP was invoked.
- X.IP \fBMAKEDIR\fP 1.4i
- XIs the full path to the initial directory in which
- X.B dmake
- Xwas invoked.
- X.IP \fBMAKEFILE\fP 1.4i
- XContains the string "-f \fImakefile\fP" where, \fImakefile\fP is the name
- Xof initial user makefile that was first read.
- X.IP \fBMAKEFLAGS\fP 1.4i
- XIs the same as $(MFLAGS) but has no leading switch
- Xcharacter. (ie. MFLAGS = -$(MAKEFLAGS))
- X.IP \fBMAKEMACROS\fP 1.4i
- XContains the complete list of macro expressions that were specified on the
- Xcommand line.
- X.IP \fBMAKETARGETS\fP 1.4i
- XContains the name(s) of the target(s), if any, that were
- Xspecified on the command line.
- X.IP \fBMAXPROCESSLIMIT\fP 1.4i
- XIs a numeric string representing the maximum number of processes that
- X\fBdmake\fP can use when making targets using parallel mode.
- X.IP \fBNULL\fP 1.4i
- XIs permanently defined to be the NULL string.
- XThis is useful when comparing a conditional expression to an NULL value.
- X.IP \fBPWD\fP 1.4i
- XIs the full path to the
- Xcurrent directory in which make is executing.
- X.IP \fBTMPFILE\fP 1.4i
- XIs set to the name of the most recent temporary file opened by \fBdmake\fP.
- XTemporary files are used for text diversions and for group recipe processing.
- X.IP \fBTMD\fP 1.4i
- XStands for "To Make Dir", and
- Xis the path from the present directory (value of $(PWD)) to the directory
- Xthat \fBdmake\fP was started up in (value of $(MAKEDIR)).
- XThis macro is modified when .SETDIR attributes are processed.
- X.IP \fBUSESHELL\fP 1.4i
- XThe value of this macro is set to "yes" if the current recipe is forced to
- Xuse a shell for its execution via the .USESHELL or '+' directives, its value
- Xis "no" otherwise.
- X.sp
- X.PP
- XThe second group of string valued macros control
- X.B dmake
- Xbehavior and may be set by the user.
- X.IP \fB.SETDIR\fP 1.6i
- XIf this macro is assigned a value then \fBdmake\fP will
- Xchange to the directory given by that value before making any targets. This
- Xmacro is equivalent to the .SETDIR attribute. Thus the two lines:
- X.sp
- X\&.SETDIR=fred/hello :
- X.sp
- X\&.SETDIR := fred/hello
- X.sp
- Xare completely equivalent. The difference being that the first is processed
- Xas a rule definition and the other as a macro.
- X.IP \fBAUGMAKE\fP 1.6i
- XIf set to a non NULL value will enable the transformation of special
- Xmeta targets to support special AUGMAKE inferences.
- X.IP \fBDIRSEPSTR\fP 1.6i
- XContains the string that is used to separate directory components when
- Xpath names are constructed. It is defined with a default value at startup.
- X.IP \fBDIVFILE\fP 1.6i
- XIs defined in the startup file and gives the name that should be used for
- Xthe diversion file name when specified as the name modifier in
- X$(mktmp ...) expansions, see the TEXT DIVERSION section for details.
- X.IP \fBGROUPFLAGS\fP 1.6i
- XThis macro gives the set of flags to pass to the shell when
- Xinvoking it to execute a group recipe. The value of the macro is the
- Xlist of flags with a leading switch indicator. (ie. `-' under UNIX)
- X.IP \fBGROUPSHELL\fP 1.6i
- XThis macro defines the full
- Xpath to the executable image to be used as the shell when
- Xprocessing group recipes. This macro must be defined if group recipes are
- Xused. It is assigned a default value in the startup makefile. Under UNIX
- Xthis value is /bin/sh.
- X.IP \fBGROUPSUFFIX\fP 1.6i
- XIf defined, this macro gives the string to use as a suffix
- Xwhen creating group recipe files to be handed to the command interpreter.
- XFor example, if it is defined as .sh, then all
- Xtemporary files created by \fBdmake\fP will end in the suffix .sh.
- XUnder MSDOS if you are using command.com as your GROUPSHELL, then this suffix
- Xmust be set to .bat in order for group recipes to function correctly.
- X.IP \fBMAKE\fP 1.6i
- XIs defined in the startup file by default.
- XThe string $(MAKE) is recognized when
- Xusing the -n option for single line recipes. Initially this macro is defined
- Xto have the value "$(MAKECMD) $(MFLAGS)".
- X.IP \fBMAKESTARTUP\fP 1.6i
- XThis macro defines the full path to the initial startup
- Xmakefile. Use the \fB-V\fP command line option to discover it's initial
- Xvalue.
- X.IP \fBMAXLINELENGTH\fP 1.6i
- XThis macro defines the maximum size of a single line of
- Xmakefile input text. The size is specified as a number, the default value
- Xis defined internally and is shown via the \fB-V\fP option.
- XA buffer of this size plus 2 is allocated for reading makefile text. The
- Xbuffer is freed before any targets are made, thereby allowing files containing
- Xlong input lines to be processed without consuming memory during the actual
- Xmake.
- X.IP \fBMAXPROCESS\fP 1.6i
- XSpecify the maximum number of child processes to use when making targets.
- XThe default value of this macro is "1" and it's value cannot exceed the value
- Xof the macro MAXPROCESSLIMIT. Setting the value of MAXPROCESS on the command
- Xline or in the makefile is equivalent to supplying a corresponding value to
- Xthe -P flag on the command line.
- X.IP \fBPREP\fP 1.6i
- XThis macro defines the number of iterations to be expanded
- Xautomatically when processing % rule definitions of the form:
- X.sp
- X% : %.suff
- X.sp
- XSee the sections on PERCENT(%) RULES for details on how PREP is used.
- X.IP \fBSHELL\fP 1.6i
- XThis macro defines the full path to the executable
- Ximage to be used as the shell when
- Xprocessing single line recipes. This macro must be defined if recipes
- Xrequiring the shell for execution are to be used.
- XIt is assigned a default value in the startup makefile.
- XUnder UNIX this value is /bin/sh.
- X.IP \fBSHELLFLAGS\fP 1.6i
- XThis macro gives the set of flags to pass to the shell when
- Xinvoking it to execute a single line recipe. The value of the macro is the
- Xlist of flags with a leading switch indicator. (ie. `-' under UNIX)
- X.IP \fBSHELLMETAS\fP 1.6i
- XEach time
- X.B dmake
- Xexecutes a single recipe line (not a group recipe) the line is
- Xsearched for any occurrence of a character defined in the value of SHELLMETAS.
- XIf such a character is found the recipe line is defined to require a shell
- Xto ensure it's correct execution. In such instances
- Xa shell is used to invoke the recipe line.
- XIf no match is found the recipe line is executed without the use of a shell.
- X.sp
- X.PP
- XThere is only one character valued macro defined by \fBdmake\fP:
- X\fBSWITCHAR\fP contains the switch character used
- SHAR_EOF
- echo "End of part 11"
- echo "File man/dmake.tf is continued in part 12"
- echo "12" > s2_seq_.tmp
- exit 0
-
-